<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<title>viewpointdevelopment</title>
		<link type="text/css" rel="stylesheet" href="PLUGINS_ROOT/org.polarsys.capella.studio.doc/html/style/style.css"/>
	</head>
	<body>
		<h1 id="Viewpoints_Development">Viewpoints Development</h1>
		<p>The abstract principles to develop viewpoints are explained in 
			<a href="https://github.com/eclipse/kitalpha/wiki/Viewpoint-development" target="_blank">Kitalpha</a>.
		</p>
		<p>Access to the page of the 
			<a href="https://github.com/eclipse-capella/capella-basic-vp/wiki" target="_blank">Basic Viewpoints</a> for existing viewpoint samples.
		</p>
		<h2 id="Development_Environment">Development Environment</h2>
		<p>Setting up the development environment is described in the 
			<a href="https://github.com/eclipse-capella/capella/wiki/Development-Environment" target="_blank">Capella wiki</a>.
		</p>
		<h2 id="Working_with_a_Viewpoint">Working with a Viewpoint</h2>
		<p>There is 2 means to start working with a viewpoint in a workspace:</p>
		<ul>
			<li>Creating a new viewpoint</li>
			<li>Importing a sample viewpoint for inspiration</li>
		</ul>
		<h2 id="Create_a_new_Viewpoint">Create a new Viewpoint</h2>
		<p>Open Capella studio and apply the commands: 
			<b>File/New…/Project – Viewpoint DSL Project</b>
			As target application can select:
		</p>
		<ul>
			<li>Capella</li>
			<li>CDO for Capella</li>
			<li>CDO and XML Metadata for Capella</li>
			<li>EMF</li>
		</ul>
		<p>
			<img height="315" width="900" border="0" src="img/viewpoint-creation.png"/> 
		</p>
		<p>Set the name, choose Capella. An Eclipse plugin is generated and the following files are present (in model):</p>
		<p>
			<img height="267" width="227" border="0" src="img/generated-vp-mass.png"/>
		</p>
		<p>You can check the 
			<a href="https://github.com/eclipse-capella/capella-basic-vp/blob/master/massviewpoint/plugins/org.polarsys.capella.vp.mass.vpdsl/model" target="_blank">capella-basic-vp</a> example.
		</p>
		<h3 id="Prerequisite_.27.27.27CDO_for_Capella.27.27.27_target">Prerequisite 
			<b>CDO for Capella</b> target
		</h3>
		<p>If 
			<b>CDO for Capella</b> is selected as target then one of the generated bundles is specific to the CDO platforms. Thus, it requires the bundle org.eclipse.emf.cdo which is not available into Capella Studio and the following steps are necessary:

			<br/>
			A new target platform is needed. To configure it:
		</p>
		<ol>
			<li>Open the preference page <code>Menu Window &gt; Preferences &gt; Plug-in development &gt; Target platform</code>.</li>
			<li>Click on the 
				<i>Add...</i> button. Then on the wizard press the 
				<i>Next</i> button.
			</li>
			<li>Click on the 
				<i>Add</i> button and select the 
				<i>installation</i> item and  press the 
				<i>Next</i> button.
			</li>
			<li>Provide the path of your CDO platform and click on 
				<i>Finish</i> button.
			</li>
			<li>Select the newly created target platform and click on 
				<i>Apply and Close</i> button.
			</li>
		</ol>
		<h3 id="Viewpoint_Aspects">Viewpoint Aspects</h3>
		<p>The 
			<b>spec.vptext</b> is the root file containing the VPDSL information.
		</p>
		<h3 id="Configuration">Configuration</h3>
		<p>The 
			<b>conf.vptext</b> will contain the configuration of the viewpoint. 
			<br/>
			Target is the targeted application. This can be Capella, CDO for Capella (targeting for instance Team for Capella), XML (generating additional files).
		</p>
		<p>
			<img height="90" width="368" border="0" src="img/conf.vptext.png"/>
		</p>
		<h3 id="Data">Data</h3>
		<p>The Data aspect is essential because information of some other aspects (e.g., UI, Diagram) is deducted from the data description.</p>
		<p>
			<img height="267" width="404" border="0" src="img/mass.data.png"/>
		</p>
		<p>In this figure, the classes Mass and PartMass have attributes and no association.</p>
		<h4 id="Inheritance">Inheritance</h4>
		<p>Inheritance is identified by the key word superClass, such as for PartMass. Mass has no inheritance. Due to the "Capella" Target Application, during the generation of the ecore file (Cf. org.polarsys.capella.vp.mass plugin), a class without superclass inherits from the Capella NamedElement class.</p>
		<p>The mechanism of inheritance enables to a have complete inheritance at the viewpoint level, not only from the data but also for the diagrams for instance.</p>
		<h4 id="Extension">Extension</h4>
		<p>An extension creates extension elements in an extended element. For Basic Mass, PartMass extends (Capella) Part. All the PartMass elements are contained by a Part element

			<img height="217" width="650" border="0" src="img/extension.png"/>
		</p>
		<h3 id="Create_a_new_Aspect">Create a new Aspect</h3>
		<p>To create a new aspect, need to use the 
			<b>mass.spec.vptext</b>.
		</p>
		<table border="1">
			<tr>
				<td>
					<p>Hit CTRL+Space: choose the new aspect to be created

						<br/>
						Modify the name of the aspect file and Finish.
					</p>
				</td>
			</tr>
		</table>
		<ul>
			<li>UI Aspect</li>
		</ul>
		<p>
			<img height="400" width="900" border="0" src="img/mass.spec.vptext-ui.png"/>
		</p>
		<ul>
			<li>Diagram Aspect</li>
		</ul>
		<p>
			<img height="395" width="918" border="0" src="img/mass.diagram.vptext.png"/>
		</p>
		<h3 id="Property_Views">Property Views</h3>
		<p>The UI contents is empty at the beginning. Populate it by 
			<b>CTRL-Space</b> and selection of the 
			<b>"UI - Generate User Interface for all classes"</b> option in the menu.

			<br/>
			The generated contents is deduced from the data description. The generation is not incremental. This means that when the Data aspect part evolves, a new generation is produced apart and ignores the previous one.

			<br/>
			By CTRL-Mouse on an attribute (e.g. mass.data.Mass.value), it is possible to navigate toward the attribute defined in the Data aspect.

			<img height="212" width="735" border="0" src="img/mass.ui.png"/>
		</p>
		<h4 id="Sirius_Property_Views">Sirius Property Views</h4>
		<p>Using Sirius Property Views in a Capella Viewpoint requires some adaptations of the tooling. It is possible but may cause some problems with existing extensions and tools integrations in Capella. For this reason we do not provide it in the Capella Studio release and the specific dependencies needs to be added.

			<br/>
			<br/>
			In order to develop your viewpoint with this capability, it is first necessary to update your Capella Studio to include the dedicated features and their dependencies.

			<br/>The Sirius update site located under: 
			<a href="https://download.eclipse.org/sirius/updates/" target="_blank">https://download.eclipse.org/sirius/updates/</a> contains the required features.

			<br/>Please use the correct repository depending on your version of capella (to get this information head to 
			<b>
				<a href="https://download.eclipse.org/capella/core/updates/releases/" target="_blank">https://download.eclipse.org/capella/core/updates/releases/</a>[YOUR_CAPELLA_VERSION_HERE]/targets/capella.target-definition.targetplatform
			</b> and check the line with Sirius).

			<br/>Then install the 
			<b>Sirius Specification Environment</b> feature.

			<br/>After installing this, the dedicated Sirius Property views will be available.

			<br/>
			You will then need to bundle you viewpoint and install it on Capella.

			<br/>
			<br/>
			In order to get it working on Capella it will be necessary to update your Capella installation and install EEF and then Sirius Specification Environment from the Sirius update site.

			<br/>As an alternative, one may add the following features as dependencies in your viewpoint build (in &lt;my_viewpoint_name&gt;.representation.feature/feature.xml or &lt;my_viewpoint_name&gt;.feature/feature.xml) and publish again the viewpoint (these files are not re-generated when publishing the viewpoint):
		</p>
		<pre>
&lt;includes id="org.eclipse.sirius.runtime.ide.eef" version="0.0.0"/&gt;
&lt;includes id="org.eclipse.sirius.properties.feature" version="0.0.0"/&gt;
&lt;includes id="org.eclipse.eef.ext.widgets.reference.feature" version="0.0.0"/&gt;
&lt;includes id="org.eclipse.eef.sdk.feature" version="0.0.0"/&gt;
</pre>
		<h3 id="Diagram">Diagram</h3>
		<p>A diagram is made of three parts: </p>
		<ol>
			<li>the diagram extension when a diagram extends an existing one,</li>
			<li>the mapping of the data onto diagram elements,</li>
			<li>the actions applicable on the diagram.</li>
		</ol>
		<p>
			<img height="180" width="807" border="0" src="img/mass.diagram.png"/>
		</p>
		<p>
			<br/>

			<b>Note:</b> Even if it is possible to generate a skeleton for diagram tools using VPDSL, the odesign file will be the place to edit and maintain diagram representations.
			<br/>
			See 
			<a href="https://github.com/eclipse-capella/capella/wiki/Tutorials" target="_blank">Sirius Tutorials</a>.
		</p>
		<h2 id="Import_existing_Viewpoint">Import existing Viewpoint</h2>
		<p>Import the vpdsl project in the Capella Studio workspace.</p>
		<p>Open the 
			<b>vptext</b> file by double-click. If an error occurs, this means that the vptext is not recognized automatically. In this case, on the vptext file, right-click and Open With Data / User Interface / Diagram / Configuration for the data / ui / diagram / conf vptext files.
		</p>
		<h2 id="Viewpoint_Description">Viewpoint Description</h2>
		<p>The viewpoint description with Kitalpha is stored in a model (.vpdesc file) and edited with a set of editors dedicated by aspect.</p>
		<p>
			<img height="180" width="788" border="0" src="img/viewpoint-description.png"/>
		</p>
		<h2 id="Generate_Viewpoint">Generate Viewpoint</h2>
		<h3 id="From_vptext">From vptext</h3>
		<p>Select the file 
			<b>conf.vptext</b> 
			<b>-&gt; Viewpoint DSL -&gt; Generate Viewpoint</b>.
		</p>
		<p>
			<img height="256" width="875" border="0" src="img/generate-vp.png"/>
		</p>
		<h3 id="From_fcore">From fcore</h3>
		<p>Some addons M2 are not generated from a .vptext but directly from an 
			<b>.fcore</b>.

			<br/>
			In this case, open the 
			<b>.fcore</b>, right click on the last FactoryComponent, and select 
			<b>"Run EGF Activity..."</b>.
		</p>
		<h3 id="Customizations">Customizations</h3>
		<p>The generated plugin 
			<b>org.polarsys.capella.vp.mass.contextual.explorer</b> must be deleted and instead add a new plugin following the tutorial on 
			<a href="/wiki/../help/topic/org.polarsys.capella.studio.doc/html/extension/tutorials/Semantic-Browser.html" title="../help/topic/org.polarsys.capella.studio.doc/html/extension/tutorials/Semantic-Browser.html">Semantic Browser</a>.
		</p>
		<h2 id="Technical_Guidelines">Technical Guidelines</h2>
		<p>To avoid performance issues, some guidelines must be followed.</p>
		<h3 id="Use_representation_descriptor_instead_of_representation">Use representation descriptor instead of representation</h3>
		<p>When an extension needs to retrieve representations (representation targeted by an element, representation per kind, representation that will be visible in documentation...) or need to store additional information about representations, please use their 
			<b>representation descriptors</b> as much as possible instead of using/storing it in the representation.
		</p>
		<p>Indeed, in a Team for Capella context, a representation is not loaded until it is accessed through descriptor.getRepresentation() (which is the case when the user opens a representation), only its descriptor is.
			Descriptor may contains the required information that fulfill your needs about representations without have to load the content of the representation and can also be used to store information about it.</p>
		<p>Please also refer to Capella Release Notes.</p>
		<h3 id="Diagram_extensions">Diagram extensions</h3>
		<h4 id="Expressions_in_.odesigns">Expressions in .odesigns</h4>
		<p>For performance reasons, when writing expressions in .odesigns it is recommended to:
<ul>
<li>Use Java Services for heavy operations.</li>
<li>Use AQL expressions for light operations.</li>
<li>
			<b>The use of Acceleo 2 is NOT supported by default and NOT recommended.</b></li>
</ul>
		</p>
		<h3 id="Semantic_Candidate_Expression">Semantic Candidate Expression</h3>
		<p>This expression called at each diagram refresh should be the most efficient possible. It can be computed based on the displayed graphical elements using the variable *diagram*. When 'Import Mapping' are used, please ensure that semantic candidate expression has been updated accordingly to the semantic candidate expression of the imported mapping</p>
		<h4 id="Create_Generic_Viewpoints">Create Generic Viewpoints</h4>
		<p>Create Generic Viewpoints using:</p>
		<ul>
			<li>Sirius capability to extends several diagrams at one time with regular expressions extensions </li>
			<li>Diagram Styles Customization Feature allowing to customize the style of elements based on expression. (for instance, on all "Functions called 'Deprecated'", set color as gray)</li>
		</ul>
		<h3 id="Migrating_your_Viewpoints">Migrating your Viewpoints</h3>
		<p>From one Version to another the Capella Metamodel can evolve and its existing classes can be modified or removed.</p>
		<p>If your Viewpoint Metamodel has any dependencies to the parts of the Capella Metamodel that evolved, then it is necessary to migrate your viewpoint. Here are the three steps that will enable you to do so:</p>
		<ol>
			<li>Migrate your existing source code. You need to ensure that your code compiles in regards to the new changes, so a rebuild of your viewpoint is necessary.</li>
			<li>Since Metamodel URIs change from one version to another it is 
				<b>imperative</b> that you replace all obsolete URIs with the new ones. Most of the time it is only a version change, for example the 
				<a href="http://www.polarsys.org/capella/core/pa/1.2.0#/" target="_blank">http://www.polarsys.org/capella/core/pa/1.2.0#/</a> URI for Capella 1.2.0 should be replaced with 
				<a href="http://www.polarsys.org/capella/core/pa/1.3.0#/" target="_blank">http://www.polarsys.org/capella/core/pa/1.3.0#/</a> for Capella 1.3.0.
			</li>
			<li>If you inherit from Metamodel classes that changed in the current version, then a migration of the models that use your viewpoint is necessary. This means that you need to contribute to the Capella Migration mechanism. Please refer to the section bellow for more details.</li>
		</ol>
		<h4 id="Contributing_to_the_Capella_Migration_mechanism">Contributing to the Capella Migration mechanism</h4>
		<p>Imagine that your viewpoint metamodel inherits from class 
			<b>A</b>. 
			In the new Capella version class 
			<b>A</b> becomes abstract and two new classes 
			<b>B</b> and 
			<b>C</b> inherit from it. This means that all instances in your model that reference class 
			<b>A</b> are obsolete and erroneous, since this class is no longer instantiable. 
		</p>
		<p>In this scenario your viewpoint needs to contribute to the native Migration mechanism and replace all the references to class 
			<b>A</b> with references to class 
			<b>B</b> or 
			<b>C</b>. This will allow existing models to become compatible with your viewpoint by simply migrating them.
		</p>
		<p>A good starting point is the 
			<b>org.polarsys.capella.core.data.migration</b> plugin that contains migration examples for the current version of Capella and especially the 
			<b>AbstractMigrationContribution</b> class that you will need to extend in order to add your custom migration logic.
		</p>
		<h3 id="Avoid_EObject.eResource_calls">Avoid EObject.eResource calls</h3>
		<p>On EObject, you have to avoid as much as possible calls to eObject.eResource()</p>
		<h3 id="Contribute_an_ID_handler">Contribute an ID handler</h3>
		<p>If your metamodel elements doesn't inherit from org.polarsys.capella.common.data.modellingcore.ModelElement, you have to contribute an Id handler via the extension point "org.polarsys.capella.shared.id.handler.IdHandler"
			You can simply extend the org.polarsys.capella.shared.id.handler.AbstractIdHandler.</p>
		<ul>
			<li>For CDO for Capella, due to #141, the generated code may not be directly compliant with the targeted application. If you inherit from a ModelElement, please ensure that the viewpoint Factory is initializing the id within the constructor, like FilteringFactoryImpl**</li>
		</ul>
	</body>
</html>